home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / usenet / sources / volume91 / utilitys / sman_1_1 / part01 / sman.doc.uu / sman.doc
Text File  |  1991-07-29  |  5KB  |  133 lines
  1.  
  2.      SMAN(1)               AMIGA Programmer's Manual                SMAN(1)
  3.  
  4.  
  5.  
  6.      ›1mNAME 
  7.           ›0msman - a document lookup program.  
  8.  
  9.      ›1mSYNOPSIS 
  10.           sman ›0m[-p Search Pattern] [-v Viewer] target [target...] 
  11.  
  12.      ›1mDESCRIPTION 
  13.           ›0mThere  is  no uniform standard for the format or position of
  14.           documentation files  on  the  Amiga.  This  makes  a  manual
  15.           program  in  the  style  of  the Unix ›4mman›0m program a somewhat
  16.           difficult thing to create.  ›4msman›0m attempts to  overcome  this
  17.           difficulty  by  allowing  the  user to specify quite general
  18.           rules for the location  of  documentation  files.    Once  a
  19.           document  is located, it is passed on to a text viewer to be
  20.           displayed.  
  21.  
  22.           There are two ways the documentation  lookup  rules  can  be
  23.           passed to  ›4msman›0m.   The first is by the use of the -›1mp ›0mcommand
  24.           line  argument,  the  second  is  by  the  ENV:  environment
  25.           variable ›1mSmanPath›0m.   The command line argument will override
  26.           any definition of the environment variable, but at least one
  27.           must be defined.  
  28.  
  29.           The format of the lookup rule is: 
  30.  
  31.                rule1;rule2;...  
  32.  
  33.           Each of the rules will be searched in order until a match is
  34.           found.  A rule is formed by an optional  special  character,
  35.           which  specifies  the  kind of search to be performed on the
  36.           matching files, followed by a (possibly) wildcarded AmigaDOS
  37.           path specifying the files to be searched.   See  ›4msregexp›0m.›4mdoc›0m
  38.           for a discussion of the wildcard format.  
  39.  
  40.           There are currently three kinds of search rules implemented: 
  41.  
  42.            ›1mDefault ›0m  If  the  rule  does  not  start  with  one of the
  43.               characters discussed below, then no  special  search  is
  44.               done  on the files on the path, and ›4msman›0m will succeed on
  45.               the first file found.    There  is  a  special  wildcard
  46.               character defined  in  sman to make this useful.  If the
  47.               character '&' is found in the search path,  it  will  be
  48.               expanded to  the  current  target.   For example, if you
  49.               typed  'sman  test'  and   ›1mSmanPath   ›0mwas   defined   as
  50.               'DOCS:.../&.(doc|man)',  then the path sman would try to
  51.               match would be 'DOCS:.../(test).(doc|man)'.  
  52.  
  53.            @  If this is the first character of the  rule,  then  sman
  54.               will assume the matched files are ›4mdme›0m.›4mrefs›0m format files,
  55.               as used  by Matt Dillon's ›4mdme›0m editor.  The files will be
  56.               searched for an entry matching the target.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.      Jon Spencer                      -1-                       Version 1.1
  66.  
  67.  
  68.      SMAN(1)               AMIGA Programmer's Manual                SMAN(1)
  69.  
  70.  
  71.            +  This type of rule tells  ›4msman›0m  the  matching  files  are
  72.               Amiga Autodoc  format files.  Each file on the path will
  73.               be search  for  an  entry  matching  the  target.    For
  74.               example,  if  ›1mSmanPath  ›0mwas  '+Autodocs:#?/#?.doc', then
  75.               'sman Write' would match to 
  76.                  'Autodocs:LibrariesA-K/dos.doc' (under 1.3 anyway).  
  77.  
  78.           All file name searches are case insensitive.   All  searches
  79.           within  a  file  (for  '+'  and  '@'  type  rules)  are case
  80.           sensitive.  
  81.  
  82.           Once ›4msman›0m has found a match, that file is passed onto a text
  83.           viewer for display.  The default viewer is ›4msless›0m,  but  this
  84.           can  be overridden by either the -›1mv ›0mcommand line argument or
  85.           the environment variable ›1mSmanViewer›0m.  If the default  viewer
  86.           is  not overridden, then both '+' and '@' style matches will
  87.           tell ›4msless›0m to start  displaying  the  file  at  the  correct
  88.           position.   If  the  default  viewer is overridden, then all
  89.           files will be displayed at the first line.  
  90.  
  91.  
  92.  
  93.      ›1mEXAMPLES 
  94.  
  95.           ›0mExample ›1mSmanPath ›0mvariable: 
  96.  
  97.               +AutoDocs:#?/#?.doc;@dcc:doc/dme.refs;@dcc:man/ me.refs; 
  98.               DOCS:.../&(.doc|.man|.txt) 
  99.  
  100.  
  101.      ›1mADDITION CONSIDERATIONS 
  102.  
  103.           ›0m›4msman›0m will always take the first match that it finds, so  the
  104.           order  of  the  rules can be used to manipulate the order of
  105.           the search.  
  106.  
  107.           Also, '@' ›4mdme›0m.›4mrefs›0m style searches are the fastest.   If  you
  108.           have  the  ›4mautorefs›0m program from Matt Dillon's ›4mDICE›0m package,
  109.           you are better off running this  on  your  Autodocs,  rather
  110.           than using the '+' style search.  
  111.  
  112.  
  113.      ›1mSEE ALSO 
  114.           ›0msless(1) 
  115.  
  116.  
  117.      ›1mBUG REPORTS 
  118.           ›0mPlease send bug reports, comments etc.  to 
  119.  
  120.                Jon Spencer 
  121.  
  122.                EMail: bhgs@gpu.utcs.utoronto.ca 
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.      Jon Spencer                      -2-                       Version 1.1
  132.  
  133.